<!-- HTML header for doxygen 1.8.13-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.14"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Taskflow Handbook</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link rel="icon" type="image/x-icon" href="favicon.ico" />
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
  $(document).ready(initResizable);
/* @license-end */</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname"><a href="https://taskflow.github.io/">Taskflow</a>
   &#160;<span id="projectnumber">3.0.0-Master-Branch</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.14 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function(){initNavTree('chapter2.html','');});
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">C2: Executor </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>After you create a task dependency graph, you need to submit it to threads for execution. In this chapter, we will show you how to execute a task dependency graph.</p>
<h1><a class="anchor" id="C2_CreateAnExecutor"></a>
Create an Executor</h1>
<p>To execute a taskflow, you need to create an <em>executor</em> of type <a class="el" href="classtf_1_1Executor.html" title="execution interface for running a taskflow graph ">tf::Executor</a>. An executor is a <em>thread-safe</em> object that manages a set of worker threads and executes tasks through an efficient <em>work-stealing</em> algorithm. Issuing a call to run a taskflow creates a <em>topology</em>, a data structure to keep track of the execution status of a running graph. <a class="el" href="classtf_1_1Executor.html" title="execution interface for running a taskflow graph ">tf::Executor</a> takes an unsigned integer to construct with <code>N</code> worker threads. The default value is <a class="elRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/thread/thread/hardware_concurrency.html">std::thread::hardware_concurrency</a>.</p>
<div class="fragment"><div class="line"><a class="code" href="classtf_1_1Executor.html">tf::Executor</a> executor1;     <span class="comment">// create an executor of std::thread::hardware_concurrency worker threads</span></div><div class="line"><a class="code" href="classtf_1_1Executor.html">tf::Executor</a> executor2(4);  <span class="comment">// create an executor of 4 worker threads</span></div></div><!-- fragment --><p>An executor can be reused to execute multiple taskflows. In most workloads, you may need only one executor to run multiple taskflows where each taskflow represents a part of a parallel decomposition.</p>
<h1><a class="anchor" id="C2_ExecuteATaskflow"></a>
Execute a Taskflow</h1>
<p><a class="el" href="classtf_1_1Executor.html" title="execution interface for running a taskflow graph ">tf::Executor</a> provides a set of <code>run_*</code> methods, <a class="el" href="classtf_1_1Executor.html#a81f35d5b0a20ac0646447eb80d97c0aa" title="runs the taskflow once ">tf::Executor::run</a>, <a class="el" href="classtf_1_1Executor.html#adca6cd0ce1bd7e6fa2ed2a55c9ae15e6" title="runs the taskflow for N times ">tf::Executor::run_n</a>, and <a class="el" href="classtf_1_1Executor.html#a8acf7515e8e8fdda366ace68bcd65aa6" title="runs the taskflow multiple times until the predicate becomes true and then invokes a callback ...">tf::Executor::run_until</a> to run a taskflow for one time, multiple times, or until a given predicate evaluates to true. All methods accept an optional callback to invoke after the execution completes, and return a <a class="elRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/thread/future.html">std::future</a> for users to access the execution status. The code below shows several ways to run a taskflow.</p>
<div class="fragment"><div class="line"> 1: <span class="comment">// Declare an executor and a taskflow</span></div><div class="line"> 2: <a class="code" href="classtf_1_1Executor.html">tf::Executor</a> executor;</div><div class="line"> 3: <a class="code" href="classtf_1_1Taskflow.html">tf::Taskflow</a> taskflow;</div><div class="line"> 4:</div><div class="line"> 5: <span class="comment">// Add three tasks into the taskflow</span></div><div class="line"> 6: <a class="code" href="classtf_1_1Task.html">tf::Task</a> A = taskflow.<a class="code" href="classtf_1_1FlowBuilder.html#a60d7a666cab71ecfa3010b2efb0d6b57">emplace</a>([] () { <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> &lt;&lt; <span class="stringliteral">&quot;This is TaskA\n&quot;</span>; });</div><div class="line"> 7: <a class="code" href="classtf_1_1Task.html">tf::Task</a> B = taskflow.<a class="code" href="classtf_1_1FlowBuilder.html#a60d7a666cab71ecfa3010b2efb0d6b57">emplace</a>([] () { <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> &lt;&lt; <span class="stringliteral">&quot;This is TaskB\n&quot;</span>; });</div><div class="line"> 8: <a class="code" href="classtf_1_1Task.html">tf::Task</a> C = taskflow.<a class="code" href="classtf_1_1FlowBuilder.html#a60d7a666cab71ecfa3010b2efb0d6b57">emplace</a>([] () { <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> &lt;&lt; <span class="stringliteral">&quot;This is TaskC\n&quot;</span>; });</div><div class="line"> 9: </div><div class="line">10: <span class="comment">// Build precedence between tasks</span></div><div class="line">11: A.<a class="code" href="classtf_1_1Task.html#a8c78c453295a553c1c016e4062da8588">precede</a>(B, C); </div><div class="line">12: </div><div class="line">13: <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/thread/future.html">std::future&lt;void&gt;</a> fu = executor.<a class="code" href="classtf_1_1Executor.html#a81f35d5b0a20ac0646447eb80d97c0aa">run</a>(taskflow);</div><div class="line">14: fu.wait();                <span class="comment">// block until the execution completes</span></div><div class="line">15:</div><div class="line">16: executor.<a class="code" href="classtf_1_1Executor.html#a81f35d5b0a20ac0646447eb80d97c0aa">run</a>(taskflow, [](){ <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> &lt;&lt; <span class="stringliteral">&quot;end of one execution\n&quot;</span>; }).wait();</div><div class="line">17: executor.<a class="code" href="classtf_1_1Executor.html#adca6cd0ce1bd7e6fa2ed2a55c9ae15e6">run_n</a>(taskflow, 4);</div><div class="line">18: executor.<a class="code" href="classtf_1_1Executor.html#ab9aa252f70e9a40020a1e5a89d485b85">wait_for_all</a>();  <span class="comment">// block until all associated executions finish</span></div><div class="line">19: executor.<a class="code" href="classtf_1_1Executor.html#adca6cd0ce1bd7e6fa2ed2a55c9ae15e6">run_n</a>(taskflow, 4, [](){ <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> &lt;&lt; <span class="stringliteral">&quot;end of four executions\n&quot;</span>; }).wait();</div><div class="line">20: executor.<a class="code" href="classtf_1_1Executor.html#a8acf7515e8e8fdda366ace68bcd65aa6">run_until</a>(taskflow, [<span class="keywordtype">int</span> cnt=0] () <span class="keyword">mutable</span> { <span class="keywordflow">return</span> (++cnt == 10); });</div></div><!-- fragment --><p>Debrief:</p>
<ul>
<li>Line 6-8 creates a taskflow of three tasks A, B, and C </li>
<li>Line 13-14 runs the taskflow once and use <a class="elRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/thread/future/wait.html">std::future::wait</a> to wait for completion </li>
<li>Line 16 runs the taskflow once with a callback to invoke when the execution finishes </li>
<li>Line 17-18 runs the taskflow four times and use <a class="el" href="classtf_1_1Executor.html#ab9aa252f70e9a40020a1e5a89d485b85" title="wait for all pending graphs to complete ">tf::Executor::wait_for_all</a> to wait for completion </li>
<li>Line 19 runs the taskflow four times and invokes a callback at the end of the forth execution </li>
<li>Line 20 keeps running the taskflow until the predicate returns true</li>
</ul>
<p>Issuing multiple runs on the same taskflow will automatically <em>synchronize</em> to a sequential chain of executions in the order of run calls.</p>
<div class="fragment"><div class="line">executor.<a class="code" href="classtf_1_1Executor.html#a81f35d5b0a20ac0646447eb80d97c0aa">run</a>(taskflow);         <span class="comment">// execution 1</span></div><div class="line">executor.<a class="code" href="classtf_1_1Executor.html#adca6cd0ce1bd7e6fa2ed2a55c9ae15e6">run_n</a>(taskflow, 10);   <span class="comment">// execution 2</span></div><div class="line">executor.<a class="code" href="classtf_1_1Executor.html#a81f35d5b0a20ac0646447eb80d97c0aa">run</a>(taskflow);         <span class="comment">// execution 3</span></div><div class="line">executor.<a class="code" href="classtf_1_1Executor.html#ab9aa252f70e9a40020a1e5a89d485b85">wait_for_all</a>();        <span class="comment">// execution 1 -&gt; execution 2 -&gt; execution 3</span></div></div><!-- fragment --><p>A key point to notice is a running taskflow must remain alive during its execution. It is your responsibility to ensure a taskflow not being destructed when it is running. For example, the code below can result undefined behavior.</p>
<div class="fragment"><div class="line"><a class="code" href="classtf_1_1Executor.html">tf::Executor</a> executor;  <span class="comment">// create an executor</span></div><div class="line"></div><div class="line"><span class="comment">// create a taskflow whose lifetime is restricted by the scope</span></div><div class="line">{</div><div class="line">  <a class="code" href="classtf_1_1Taskflow.html">tf::Taskflow</a> taskflow;</div><div class="line">  </div><div class="line">  <span class="comment">// add tasks to the taskflow</span></div><div class="line">  <span class="comment">// ... </span></div><div class="line"></div><div class="line">  <span class="comment">// run the taskflow</span></div><div class="line">  executor.<a class="code" href="classtf_1_1Executor.html#a81f35d5b0a20ac0646447eb80d97c0aa">run</a>(f);</div><div class="line"></div><div class="line">} <span class="comment">// at this point, taskflow might get destructed while it is running, resulting in undefined behavior</span></div></div><!-- fragment --><p>Similarly, you should avoid touching a taskflow while it is running.</p>
<div class="fragment"><div class="line"><a class="code" href="classtf_1_1Taskflow.html">tf::Taskflow</a> taskflow;</div><div class="line"></div><div class="line"><span class="comment">// Add tasks into the taskflow</span></div><div class="line"><span class="comment">// ...</span></div><div class="line"></div><div class="line"><span class="comment">// Declare an executor</span></div><div class="line"><a class="code" href="classtf_1_1Executor.html">tf::Executor</a> executor;</div><div class="line"></div><div class="line"><a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/thread/future.html">std::future&lt;void&gt;</a> future = taskflow.run(f);  <span class="comment">// non-blocking return</span></div><div class="line"></div><div class="line"><span class="comment">// alter the taskflow while running leads to undefined behavior </span></div><div class="line">f.<a class="code" href="classtf_1_1FlowBuilder.html#a60d7a666cab71ecfa3010b2efb0d6b57">emplace</a>([](){ <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> &lt;&lt; <span class="stringliteral">&quot;Add a new task\n&quot;</span>; });</div></div><!-- fragment --><p>A rule of thumb is to always keep a taskflow alive in your function scope while it is participating in an execution.</p>
<h1><a class="anchor" id="C2_ThreadSafety"></a>
Thread Safety</h1>
<p>All <code>run_*</code> methods are <em>thread-safe</em>. You can have multiple threads call these methods from an executor to run different taskflows. However, the order which taskflow runs first is non-deterministic and is up to the runtime.</p>
<div class="fragment"><div class="line">1: <a class="code" href="classtf_1_1Executor.html">tf::Executor</a> executor;</div><div class="line">2:</div><div class="line">3: <span class="keywordflow">for</span>(<span class="keywordtype">int</span> i=0; i&lt;10; ++i) {</div><div class="line">4:   <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/thread/thread.html">std::thread</a>([i, &amp;](){</div><div class="line">5:     <span class="comment">// ... modify my taskflow</span></div><div class="line">6:     executor.<a class="code" href="classtf_1_1Executor.html#a81f35d5b0a20ac0646447eb80d97c0aa">run</a>(taskflows[i]);  <span class="comment">// run my taskflow</span></div><div class="line">7:   }).detach();</div><div class="line">8: }</div></div><!-- fragment --><p>It is your responsibility to ensure all taskflows from different threads remain alive during their executions; or it can result unexpected behavior or program crash.</p>
<h1><a class="anchor" id="C2_Async"></a>
Run a Task Asynchronously</h1>
<p>In addition to run a taskflow, the executor provides a STL-styled method, <a class="el" href="classtf_1_1Executor.html#a1e6866c8f1b6a2e932f06d0b4eb032c0" title="runs a given function asynchronously ">tf::Executor::async</a>, for you to run a callable object (e.g., function) asynchronously. A common use case of the method is using the executor as a thread pool.</p>
<div class="fragment"><div class="line"><a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/thread/future.html">std::future&lt;int&gt;</a> future = executor.<a class="code" href="classtf_1_1Executor.html#a1e6866c8f1b6a2e932f06d0b4eb032c0">async</a>([](){</div><div class="line">  <span class="comment">// do some heavy work</span></div><div class="line">  <span class="comment">// ...</span></div><div class="line">  <span class="keywordflow">return</span> 1;</div><div class="line">});</div><div class="line">executor.<a class="code" href="classtf_1_1Executor.html#ab9aa252f70e9a40020a1e5a89d485b85">wait_for_all</a>();</div><div class="line">assert(future.get() == 1);</div></div><!-- fragment --><p>The method, <a class="el" href="classtf_1_1Executor.html#a1e6866c8f1b6a2e932f06d0b4eb032c0" title="runs a given function asynchronously ">tf::Executor::async</a>, is <em>thread-safe</em> and can be called from any threads or from the execution of a task. Our scheduler autonomously detects whether the async task is submitted from an external thread or a worker thread and executes it in the work-stealing loop.</p>
<div class="fragment"><div class="line">taskflow.<a class="code" href="classtf_1_1FlowBuilder.html#a60d7a666cab71ecfa3010b2efb0d6b57">emplace</a>([&amp;](){</div><div class="line">  <span class="comment">// do some work</span></div><div class="line">  <span class="comment">// ...</span></div><div class="line">  <span class="comment">// launch a task asynchronously</span></div><div class="line">  executor.<a class="code" href="classtf_1_1Executor.html#a1e6866c8f1b6a2e932f06d0b4eb032c0">async</a>([](){</div><div class="line">    <span class="comment">// do another asynchronous work </span></div><div class="line">  })</div><div class="line">});</div><div class="line">executor.<a class="code" href="classtf_1_1Executor.html#a81f35d5b0a20ac0646447eb80d97c0aa">run</a>(taskflow);</div><div class="line">executor.<a class="code" href="classtf_1_1Executor.html#ab9aa252f70e9a40020a1e5a89d485b85">wait_for_all</a>();   <span class="comment">// wait for all tasks to finish</span></div></div><!-- fragment --><p>The future object returned from the <a class="el" href="classtf_1_1Executor.html#a1e6866c8f1b6a2e932f06d0b4eb032c0" title="runs a given function asynchronously ">tf::Executor::async</a> call does not block on destruction.</p>
<h1><a class="anchor" id="C2_Observer"></a>
Observe Thread Activities</h1>
<p>You can observe thread activities in an executor when a worker thread participates in executing a task and leaves the execution using <a class="el" href="classtf_1_1ObserverInterface.html" title="The interface class for creating an executor observer. ">tf::ObserverInterface</a> &ndash; an <em>interface</em> class that provides a set of methods for you to define what to do when a thread enters and leaves the execution context of a task.</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>ObserverInterface {</div><div class="line">  <span class="keyword">virtual</span> <a class="code" href="classtf_1_1ObserverInterface.html#adfd71c3af3ae2ea4f41eed26c1b6f604">~ObserverInterface</a>() = <span class="keywordflow">default</span>;</div><div class="line">  <span class="keyword">virtual</span> <span class="keywordtype">void</span> <a class="code" href="classtf_1_1ObserverInterface.html#a41e6e62f12bf9d9dc4fa74632f6825d9">set_up</a>(<span class="keywordtype">size_t</span> num_workers) = 0;</div><div class="line">  <span class="keyword">virtual</span> <span class="keywordtype">void</span> <a class="code" href="classtf_1_1ObserverInterface.html#afa57654edd6d0fcf188a6064823f3048">on_entry</a>(<span class="keywordtype">size_t</span> worker_id, <a class="code" href="classtf_1_1TaskView.html">tf::TaskView</a> task_view) = 0;</div><div class="line">  <span class="keyword">virtual</span> <span class="keywordtype">void</span> <a class="code" href="classtf_1_1ObserverInterface.html#a8fcff02bfcea581d280e4de0247760d3">on_exit</a>(<span class="keywordtype">size_t</span> worker_id, <a class="code" href="classtf_1_1TaskView.html">tf::TaskView</a> task_view) = 0;</div><div class="line">};</div></div><!-- fragment --><p>There are three methods you must define in your derived class, <a class="el" href="classtf_1_1ObserverInterface.html#a41e6e62f12bf9d9dc4fa74632f6825d9" title="constructor-like method to call when the executor observer is fully created ">tf::ObserverInterface::set_up</a>, <a class="el" href="classtf_1_1ObserverInterface.html#afa57654edd6d0fcf188a6064823f3048" title="method to call before a worker thread executes a closure ">tf::ObserverInterface::on_entry</a>, and <a class="el" href="classtf_1_1ObserverInterface.html#a8fcff02bfcea581d280e4de0247760d3" title="method to call after a worker thread executed a closure ">tf::ObserverInterface::on_exit</a>. The method, <a class="el" href="classtf_1_1ObserverInterface.html#a41e6e62f12bf9d9dc4fa74632f6825d9" title="constructor-like method to call when the executor observer is fully created ">tf::ObserverInterface::set_up</a>, is a constructor-like method that will be called by the executor when the observer is constructed. It passes an argument of the number of workers to observer in the executor. You may use it to preallocate or initialize data storage, e.g., an independent vector for each worker. The methods, <a class="el" href="classtf_1_1ObserverInterface.html#afa57654edd6d0fcf188a6064823f3048" title="method to call before a worker thread executes a closure ">tf::ObserverInterface::on_entry</a> and <a class="el" href="classtf_1_1ObserverInterface.html#a8fcff02bfcea581d280e4de0247760d3" title="method to call after a worker thread executed a closure ">tf::ObserverInterface::on_exit</a>, are called by a worker thread before and after the execution context of a task, respectively. You may use them to record timepoints and calculate the elapsed time of a task.</p>
<p>You can associate an executor with one or multiple observers (though one is common) using <a class="el" href="classtf_1_1Executor.html#a3e68a0d779cfee1554c88c2596ae9000" title="constructs an observer to inspect the activities of worker threads ">tf::Executor::make_observer</a>. We use <a class="elRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/memory/shared_ptr.html">std::shared_ptr</a> to manage the ownership of an observer. The executor loops through each observer and invoke the corresponding methods accordingly.</p>
<div class="fragment"><div class="line"> 1 #include &lt;taskflow/taskflow.hpp&gt;</div><div class="line"> 2</div><div class="line"> 3 <span class="keyword">struct </span>MyObserver : <span class="keyword">public</span> <a class="code" href="classtf_1_1ObserverInterface.html">tf::ObserverInterface</a> {</div><div class="line"> 4</div><div class="line"> 5   MyObserver(<span class="keyword">const</span> <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/string/basic_string.html">std::string</a>&amp; name) {</div><div class="line"> 6     <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> &lt;&lt; <span class="stringliteral">&quot;constructing observer &quot;</span> &lt;&lt; name &lt;&lt; <span class="charliteral">&#39;\n&#39;</span>;</div><div class="line"> 7   }</div><div class="line"> 8</div><div class="line"> 9   <span class="keywordtype">void</span> set_up(<span class="keywordtype">size_t</span> num_workers) <span class="keyword">override</span> <span class="keyword">final</span> {</div><div class="line">10     <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> &lt;&lt; <span class="stringliteral">&quot;settting up observer with &quot;</span> &lt;&lt; num_workers &lt;&lt; <span class="stringliteral">&quot; workers\n&quot;</span>;</div><div class="line">11   }</div><div class="line">12</div><div class="line">13   <span class="keywordtype">void</span> on_entry(<span class="keywordtype">size_t</span> w, <a class="code" href="classtf_1_1TaskView.html">tf::TaskView</a> tv) <span class="keyword">override</span> <span class="keyword">final</span> {</div><div class="line">14     <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostringstream.html">std::ostringstream</a> oss;</div><div class="line">15     oss &lt;&lt; <span class="stringliteral">&quot;worker &quot;</span> &lt;&lt; w &lt;&lt; <span class="stringliteral">&quot; ready to run &quot;</span> &lt;&lt; tv.name() &lt;&lt; <span class="charliteral">&#39;\n&#39;</span>;</div><div class="line">16     <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> &lt;&lt; oss.str();</div><div class="line">17   }</div><div class="line">18</div><div class="line">19   <span class="keywordtype">void</span> on_exit(<span class="keywordtype">size_t</span> w, <a class="code" href="classtf_1_1TaskView.html">tf::TaskView</a> tv) <span class="keyword">override</span> <span class="keyword">final</span> {</div><div class="line">20     <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostringstream.html">std::ostringstream</a> oss;</div><div class="line">21     oss &lt;&lt; <span class="stringliteral">&quot;worker &quot;</span> &lt;&lt; w &lt;&lt; <span class="stringliteral">&quot; finished running &quot;</span> &lt;&lt; tv.name() &lt;&lt; <span class="charliteral">&#39;\n&#39;</span>;</div><div class="line">22     <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> &lt;&lt; oss.str();</div><div class="line">23   }</div><div class="line">24</div><div class="line">25 };</div><div class="line">26</div><div class="line">27 <span class="keywordtype">int</span> main(){</div><div class="line">28</div><div class="line">29   <a class="code" href="classtf_1_1Executor.html">tf::Executor</a> executor(4);</div><div class="line">30</div><div class="line">31   <span class="comment">// Create a taskflow of eight tasks</span></div><div class="line">32   <a class="code" href="classtf_1_1Taskflow.html">tf::Taskflow</a> taskflow;</div><div class="line">33</div><div class="line">34   <span class="keyword">auto</span> A = taskflow.<a class="code" href="classtf_1_1FlowBuilder.html#a60d7a666cab71ecfa3010b2efb0d6b57">emplace</a>([] () { <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> &lt;&lt; <span class="stringliteral">&quot;1\n&quot;</span>; }).name(<span class="stringliteral">&quot;A&quot;</span>);</div><div class="line">35   <span class="keyword">auto</span> B = taskflow.<a class="code" href="classtf_1_1FlowBuilder.html#a60d7a666cab71ecfa3010b2efb0d6b57">emplace</a>([] () { <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> &lt;&lt; <span class="stringliteral">&quot;2\n&quot;</span>; }).name(<span class="stringliteral">&quot;B&quot;</span>);</div><div class="line">36   <span class="keyword">auto</span> C = taskflow.<a class="code" href="classtf_1_1FlowBuilder.html#a60d7a666cab71ecfa3010b2efb0d6b57">emplace</a>([] () { <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> &lt;&lt; <span class="stringliteral">&quot;3\n&quot;</span>; }).name(<span class="stringliteral">&quot;C&quot;</span>);</div><div class="line">37   <span class="keyword">auto</span> D = taskflow.<a class="code" href="classtf_1_1FlowBuilder.html#a60d7a666cab71ecfa3010b2efb0d6b57">emplace</a>([] () { <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> &lt;&lt; <span class="stringliteral">&quot;4\n&quot;</span>; }).name(<span class="stringliteral">&quot;D&quot;</span>);</div><div class="line">38   <span class="keyword">auto</span> E = taskflow.<a class="code" href="classtf_1_1FlowBuilder.html#a60d7a666cab71ecfa3010b2efb0d6b57">emplace</a>([] () { <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> &lt;&lt; <span class="stringliteral">&quot;5\n&quot;</span>; }).name(<span class="stringliteral">&quot;E&quot;</span>);</div><div class="line">39   <span class="keyword">auto</span> F = taskflow.<a class="code" href="classtf_1_1FlowBuilder.html#a60d7a666cab71ecfa3010b2efb0d6b57">emplace</a>([] () { <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> &lt;&lt; <span class="stringliteral">&quot;6\n&quot;</span>; }).name(<span class="stringliteral">&quot;F&quot;</span>);</div><div class="line">40   <span class="keyword">auto</span> G = taskflow.<a class="code" href="classtf_1_1FlowBuilder.html#a60d7a666cab71ecfa3010b2efb0d6b57">emplace</a>([] () { <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> &lt;&lt; <span class="stringliteral">&quot;7\n&quot;</span>; }).name(<span class="stringliteral">&quot;G&quot;</span>);</div><div class="line">41   <span class="keyword">auto</span> H = taskflow.<a class="code" href="classtf_1_1FlowBuilder.html#a60d7a666cab71ecfa3010b2efb0d6b57">emplace</a>([] () { <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> &lt;&lt; <span class="stringliteral">&quot;8\n&quot;</span>; }).name(<span class="stringliteral">&quot;H&quot;</span>);</div><div class="line">42 </div><div class="line">43   <span class="comment">// create an observer</span></div><div class="line">44   <a class="codeRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/memory/shared_ptr.html">std::shared_ptr&lt;MyObserver&gt;</a> observer = executor.<a class="code" href="classtf_1_1Executor.html#a3e68a0d779cfee1554c88c2596ae9000">make_observer</a>&lt;MyObserver&gt;(<span class="stringliteral">&quot;MyObserver&quot;</span>);</div><div class="line">45 </div><div class="line">46   <span class="comment">// run the taskflow</span></div><div class="line">47   executor.<a class="code" href="classtf_1_1Executor.html#a81f35d5b0a20ac0646447eb80d97c0aa">run</a>(taskflow).get();</div><div class="line">48 </div><div class="line">49   <span class="comment">// remove the observer (optional)</span></div><div class="line">50   executor.<a class="code" href="classtf_1_1Executor.html#a31081f492c376f7b798de0e430534531">remove_observer</a>(std::move(observer));</div><div class="line">51 </div><div class="line">52   <span class="keywordflow">return</span> 0;</div><div class="line">53 }</div></div><!-- fragment --><p>The above code produces the following output:</p>
<div class="fragment"><div class="line">constructing observer MyObserver</div><div class="line">setting up observer with 4 workers</div><div class="line">worker 2 ready to run A</div><div class="line">1</div><div class="line">worker 2 finished running A</div><div class="line">worker 2 ready to run B</div><div class="line">2</div><div class="line">worker 1 ready to run C</div><div class="line">worker 2 finished running B</div><div class="line">3</div><div class="line">worker 2 ready to run D</div><div class="line">worker 3 ready to run E</div><div class="line">worker 1 finished running C</div><div class="line">4</div><div class="line">5</div><div class="line">worker 1 ready to run F</div><div class="line">worker 2 finished running D</div><div class="line">worker 3 finished running E</div><div class="line">6</div><div class="line">worker 2 ready to run G</div><div class="line">worker 3 ready to run H</div><div class="line">worker 1 finished running F</div><div class="line">7</div><div class="line">8</div><div class="line">worker 2 finished running G</div><div class="line">worker 3 finished running H</div></div><!-- fragment --><p>It is expected each line of <a class="elRef" doxygen="/Users/twhuang/PhD/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml:http://en.cppreference.com/w/" href="http://en.cppreference.com/w/cpp/io/basic_ostream.html">std::cout</a> interleaves with each other as there are four workers participating in task scheduling. However, the <em>ready</em> message always appears before the corresponding task message (e.g., numbers) and then the <em>finished</em> message. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="navelem"><a class="el" href="Cookbook.html">Cookbook</a></li>
    <li class="footer">Generated by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.14 </li>
  </ul>
</div>
</body>
</html>
